Using the formula builder to configure an advanced formula

1. In the IEE application, go to Meter Data Management > Application Data > Interactive Graphing.

2. Select a service point channel.

3. Select the Formula tab.

4. Select the Advanced tab. The Expression Builder window appears.

5. Click Build Formula.

   This button appears in a window only if the Formula Builder is available.

   or

   Select Meter Data Management > Application Data > Named Formulas.

   The Formula Builder dialog appears.

6. Select the Advanced tab.

   Enter the formula directly into the white board, or use the Expression Builder tool.

7. Click Builder to open the Expression Builder dialog.

8. Within the Expression Builder, navigate through a categorized tree of UCE tokens. As you click each category (folder) or UCE token, the Expression Builder displays descriptions and examples that help simplify the formula building process.

   Functions: see Functions for additional details on the functions available here.

   The Functions folder contains the following subcategories:

   • Conversion

     These functions convert from one or more units to a target unit and support power triangle conversions.

     Table 60 Functions

     Term	Definition
     Ampsi2h	sqrt(IPH*args[0].value)
     I2hi	SQ(args[0].value)/IPH
     I2hih	SQ(args[0].value*IPH)/IPH
     I4hi2h	IPH*SQ(args[0].value)
     Ihi2h	sqrt(args[0].value*IPH/IPH
     Kqhvarh	(args[1].value*SQRT3+args[0].value)/2
     Kvah	SQRT_SUM_SQS(args[0].value,args[1].value)
     Kvarh	SQRT_DIFF_SQS(args[1].value,args[0].value)
     Kvarhq	(2*args[1].value)-args[0].value/sqrt(3)
     Kwh	SQRT_DIFF_SQS(args[1].value,args[0].value)
     Pf	args[0].value/SQRT_SUM_SQS(args[0].value,args[1].value))
     Pfwva	divide(req,args[0].value,args[1].value)
     V2hv	SQ(args[0].value)/IPH
     V2hvh	SQ(args[0].value*IPH)/IPH
     V4hv2h	IPH*SQ(args[0].value)
     Vhv2h	sqrt(args[0].value*IPH)/IPH
     Voltsv2h	sqrt(IPH*args[0].value)

   • Date

     All quantities returned by the date functions are represented as floating point values, so a time of noon returned by @time would be equal to a value of 120000.0. The @holiday function returns 1.0 if the local time of the current interval falls within a day defined to be a holiday, 0.0 otherwise. In all the functions, the argument is the current interval of the given channel.

     Table 61 Dates

     Term	Definition
     Date	The date in YYYYMMDD format
     Datetime	The datetime in YYYYMMDDHHMMSS format
     Day	A number from 1-31 signifying day of the month
     Daytype	Returns a number from 1-7 where Sunday=1
     Holiday	Is the interval on a holiday or not. 1.0 for true or 0.0 for false. For more information about creating Holiday Lists, see Holiday lists.
     Month	A number from 1-12 where January=1
     Time	The time in HHMMSS format
     Year	The year, for example 1999, 2009

     Note: Holidays must be included in a Holiday List called Default for the holidays to apply when IEE generates baselines. Holidays included in other lists are not considered holidays with respect to baselines.

     Table 62 Dates

     Term	Definition
     Date	The date in YYYYMMDD format
     Datetime	The datetime in YYYYMMDDHHMMSS format
     Day	A number from 1-31 signifying day of the month
     Daytype	Returns a number from 1-7 where Sunday=1
     Holiday	Is the interval on a holiday or not. 1.0 for true or 0.0 for false. For more information about creating Holiday Lists, see Holiday lists.
     Month	A number from 1-12 where January=1
     Time	The time in HHMMSS format
     Year	The year, for example 1999, 2009

   • Inline Scalar

     These functions return a single value and can be used anywhere inside a formula. Scalar IF (SIF) returns 1.0 for true and 0.0 for false.

     Table 63 Terms

     Term	Definition
     Avg	The scalar average across the interval stream
     Lf	Compute load factor, defined as total usage/(max demand*total time), in hrs
     NLow	Returns the nth low
     NPeak	Returns the nth peak
     SAbs	Currently always returns 0
     SIf	Returns 1 if expr is true, 0 otherwise.
     Status Count	Returns the number of times given status appears in the interval stream
     Sum	The scalar sum across the interval stream
     Zero Count	Total number of zero intervals (tolerance of 0.00001)

   • Math

     These functions can take as an argument any expression that results in a channel stream of interval data. The functions for vector sum, average, min and max take a list of such expressions (which could just be channel references), optionally followed by a list of named exclude conditions.

     Table 64 Terms

     Term	Definition
     Abs	The absolute value of the argument
     Arccos	Arccosine returns a value in the range 0 to 180 degrees and assume argument is between -1 and 1, non-inclusive
     Arcsin	Arcsine returns a value in the range of 0 to 180 degrees and assume argument is between -1 and 1, non-inclusive
     Arctan	Arctan returns a value in the range of -90 to 90 degrees
     Cos	Cosine of the argument. Argument assumed to be in degrees
     IAvg	Takes two or more arguments and returns avg. Allows exclude conditions. For explicity defined channels
     IAvg (Group)	Takes the service point channels included in a configuration group and returns avg. Allows exclude conditions.
     If	Standard "if" operation
     IMax	Takes two or more arguments and returns max. Allows exclude conditions
     IMax (Group)	Takes the service point channels included in a configuration group and returns max. Allows exclude conditions.
     IMin	Takes two or more arguments and returns min. Allows exclude conditions
     IMin (Group)	Takes the service point channels included in a configuration group and returns min. Allows exclude conditions.
     ISum	Takes two or more arguments and returns sum. Allows exclude conditions
     ISum (Group)	Takes the service point channels included in a configuration group and returns sum. Allows exclude conditions.
     Neg	The argument unless argument is >0, then 0
     Pos	The argument unless argument is <0, then 0
     Sin	Sine of the argument. Argument to be in degrees
     Sqrt	Square root of the argument. Assumes argument >0
     Square	The argument squared
     Tan	Tangent of the argument. Argument assumed to be in degrees

   • Special

     Table 65 Special terms

     Term	Definition
     Demand	The demand will convert the interval data stream to demand values appropriate to the output unit of measure
     Energy	Energy is a no-op solely for documentation purposes
     Primary	Primary is a special function that converts the literal service point channel to 'primary' instead of secondary units
     Profile Register Data	Computes interval data from a consumption register channel and a load shape channel. Example: @profilereg(A:101,B:1), where A:101 is a consumption register channel and B:1 is an interval channel containing the loadshape to use. This function can only be used in a stored formula channel, at the top level of a formula, and it must be aggregated for the exact time ranges of the register values. The first parameter must be any supported type of explicit reference to a register channel (service point ID ‘:’ channel number, $sp, $spc, etc.). The second parameter can be any expression which evaluates to an interval stream.
     Pulse	Pulse only takes a few specific arguments: either a single, literal service point channel reference, or a @kqhvarh function whose kvarh argument is a single, literal service point channel reference. The formula used is Round((Value+Pulse offset)/(Pulse Multiplier))
     Register Usage	Returns the consumption, in KWH, for a consumption register channel. Example: @regusage(A:1), where A:1 is a consumption register channel. They must be aggregated for the exact time ranges of the register values. There must be a read on the register channel at the start and end of the aggregation or at the start and end of another requested time span. Critical changes (such as meter swaps) are supported as long as there is an end read at the exact time of the change and a start read also at the same time. Only physical register channels can be the source for this function. If the source is not a physical register channel, no readings are returned and an error displays.
     Secondary	Secondary is a special function that converts the literal service point channel to 'secondary' instead of primary units.
     TransformerLosses	Calculates transformer losses using the same T model used in MV-90. Example: @tlosses(A:1,0.0002,0.0141,W,A:5,NA) calculates the losses against A:1, where 0.0002 is ILC, 0.0141 is CLC, the service type is W, A:5 is a V2H channel, and NA specifies that there is no I2H channel.

   • Status Validation

     Queries or sets status information for an interval.

     Table 66 Statuses

     Term	Definition
     Set	Takes an optional list of status conditions (or negated status conditions) and applies those status conditions and the given expression to form an interval value
     Status	Returns 1.0 if the interval has the specified statuses. These can be combined in AND or OR fashion.

   • Top-level Scalar

     These functions may only appear at the very top level of a formula. They return scalar values and will set the isScalar field of the IntervalData object to true. The peak and low functions will return the 'n' highest (or lowest) values found. Coincidence peak and low functions take exactly two arguments. 'aggregate' represents the aggregated interval stream. The interval from the 'contributor' channel at the time of the peak or low will be returned.

     Table 67 Terms

     Term	Definition
     Scalar Average	Computes the average across the stream of data
     Scalar Coincident Lows	Finds the first low in 'aggregate' and returns the coincident value from 'contributor'. Must give exactly 2 expressions
     Scalar Coincident Peaks	Finds the first peak in 'aggregate' and returns the coincident value from 'contributor'. Must give exactly 2 expressions
     Scalar Low	Returns the 'n' lowest value in the interval stream
     Scalar Peak	Returns the 'n' highest value in the interval stream
     Scalar Sum	Computes the sum across the stream of data

   Operators 

   The Operators folder contains the following subcategories:

   • Arithmetic

     Table 68 Terms

     Term	Definition
     -	Subtraction
     --	Decrement
     ()	Parentheses
     *	Multiplication
     /	Division
     ^	Exponentiation
     |	Bitwise OR
     +	Addition
     ++	Increment

   • Comparison

     Table 69 Terms

     Term	Definition
     !=	Not Equal
     <	Less than
     <=	Less than or equal
     =	Equal
     >	Greater than
     >=	Greater than or equal

   • Logical

     Table 70 Terms

     Term	Definition
     AND	Logical AND
     NOT	Logical NOT
     OR	Logical OR

Options

The Options folder contains the following subcategory:

Summary Statistic Options

Table 71 Terms

Term	Definition
Daily Statistics	Summarize statistics for each local time calendar day
Monthly Statistics	Summarize statistics for each local time calendar month
Weekly Statistics	Summarize statistics for each week. Week begins on Sunday at midnight, local time

Variables

The Variables folder contains the following subcategory:

Dynamic Variables

Table 72 Variables

Term	Definition
Input	Use passed-in data as service point
Input:	Use passed-in data as service point channel, specify as '$input:n'
Iph	Number of intervals per hour
Num Intervals	Total number of intervals
Sp	Output service point, specify as '$sp:n'
Spc	Output service point channel
Usage Value	Current interval value as usage

Note: Advanced formula supports either variable $input or $input:XX, but not if both are used in the same formula.

1. Select a token and click Add, or double-click a token directly to add it to the formula work space.

2. Click Search to open the standard IEE search dialog to search for entities to add to the formula.

3. Click OK when the formula (or the part you are creating using the Expression Builder) is configured.

   The Expression Builder dialog closes and the formula segment you built displays on the white board at the cursor.

   If there is a logical inconsistency in the formula, a warning message appears. Make the appropriate corrections and click OK.

4. Click OK when the formula (or the part you are creating using the Expression Builder) is configured.

   The Expression Builder dialog closes and the formula segment you built displays on the white board at the cursor.

   If there is a logical inconsistency in the formula, a warning message appears. Make the appropriate corrections and click OK.

5. Click Validate to check formula logic and verify the complete formula works.

   If the configuration works, a confirmation message appears. If there is a logical incompatibility, an error message appears.

   Caution: The Validate button validates formula logic. It does not validate interval data.

6. Click OK. The formula is entered into the formula field.